# Grav

Grav é uma ferramenta pra fazer blogs e sites, e provavelmente a nossa melhor chance de substituir inteiramente o wordpress, satisfazendo a necessidade de todo mundo que insiste em continuar usando wordpress.

[[!toc levels=6]]

---

# Passo a passo do desenvolvimento do site em Grav

1. Feito o logo em SVG com Inkscape.

2. Foi feito um mock-up de como seria o design do site. Escolhida a disposição do conteúdo e a paleta de cores. Como o objetivo é ser o mais acessível possível, o design foi pensado com foco em mobile - e depois expandido para a versão desktop.

3. A página inicial foi montada em HTML + CSS. Objetivo utilizar o mínimo possível de Javascript (se não nenhum) para que a página possa ser totalmente compatível com Tor.

4. Analisadas algumas opções de gerenciadores de conteúdos (CMS). De acordo com a filosofia das administradoras do site, era essencial ser software livre. Passando por Wordpress e Ikiwiki, chegou-se ao Grav (<https://www.getgrav.org/>), sob licença MIT. Entre as vantagens do Grav: ser relativamente simples, ter diversos temas e plugins já desenvolvidos e extensa documentação disponível online - em inglês (<https://learn.getgrav.org/>).

5. **Para utilizar e desenvolver para Grav na máquina local, foram instalados:**

* Sublime
* MAMP: My Apache - MySQL - PHP (<https://www.mamp.info/en/>)
* PHP 5.5.31 (atualizado)
* Composer: gerenciador de dependências PHP (<https://getcomposer.org/>)
* Twig (<http://twig.sensiolabs.org/>)

6. Feito estudo da documentação e funcionalidades do Grav.

7. Definidos os tipos de páginas do site para desenvolvimento do tema.

* Index (modular). A base para todas as outras páginas. Precisa poder incorporar as outras "partes" de acordo com a categoria selecionada.

* Blog (listing). Condensar para exibir cada página de artigo
	-> cada artigo: child page
* Ferramentas (listing). Condensar para exibir cada página de artigo. Um artigo por ferramenta.
	-> cada artigo: child page
* Aprenda. (listing). Condensar para exibir cada artigo de indicação de ferramenta da aprendizagem (Coursera, CodeAcademy, etc.)
	-> cada artigo: child page
* Quem Somos (standard).
* Encontros (standard).
* Conecte-se (standard).
* Manifesto (standard).
* Termos de uso (standard)

8. Feito:

* OK - A barra de navegação aparecer em todas as páginas que não a inicial. Resolvido usando outro partial pras outras páginas.

* OK - Layout do blog: posts como "alvenaria vertical" (Masonry) nas versões tablet e desktop. Tentado com flexboxes. Resolvido com column-count, column-gap, column-break-inside e page-break-inside. 

* OK - Resolver o problema do single-post que não aparece o conteúdo da página. Resolvido com {{ page.content }} <code>*shame on me*</code>

* OK - Layout/CSS do artigo do blog e imagem do blog

* OK - Canary watch

* OK - Página de colaboração

* OK - Configuração para artigos no blog e artigos em "ferramentas", criando "ferramentas.html.twig", /partials/ferramentas_item.html.twig e configurando header da "page" Ferramentas.

* OK - Feita a página "tudo" para exibir todos os posts. É possível, sim, ter mais de um "blog" no site, tendo uma coleção de artigos por página. Para exibir os posts de todos os "blogs" em uma página só, editado o header do markdown dessa página da seguinte forma:


            content:

            items:

            - '@page.children': '/blog'

            - '@page.children': '/ferramentas'

            - '@page.children': '/aprenda'

            - '@page.children': '/encontros'

É possível também mesclar page.children e outras coleções com as tags.Documentação para detalhes desse processo: <https://learn.getgrav.org/content/collections>. 

* OK - Aliás, descobrir como exibir as tags no final do "resumo" dos posts na página do blog. -> *Aparentemente, basta colocar as tags no header do markdown >.<*

* OK - Ajeitar a classe de botão ativo na barra de navegação. -> Feito mudando a barra de navegação para valor variável e usando um "if page.visible set current_page = (page.active)..." Também foi ajeitada a barra de navegação para ficar decente em qualquer layout, teoricamente.

* OK - Arrumar navegação entre os posts "related/next" no blog -> Descobrir como fazer isso, para começo de conversa. Mundo ideal: que a navegação entre os posts seja possível pelas setas do teclado, como é no site da documentação do Grav. -> Foi arrumada a navegação, porém/todavia/contudo/entretanto o hover do "next" está sendo mal-comportado e não funciona de jeito nenhum por algum motivo que não consigo descobrir qual. Também ainda não descobri como resolver para fazer uma navegação fodástica com font-awesome + teclado, como na documentação do Grav. >.<

* OK - 404: not found (standard)

* OK - Adicionado plugin de comentários e ajeitado o design. 

* OK - Instalado plugin de RSS e colocado link para o RSS de todos os posts no footer. 

* OK - Criar outras páginas/elementos, de preferência do Jeito Certo&trade;

* OK - Comentários só nos artigos e não em páginas gerais como "blog" - isso foi feito do Jeito Certo&trade editando o .yaml do plugin comments.

* OK - Plugins: Instalado plugin de RSS, falta colocar nas respectivas páginas o botão para inscrição. Sitemap. Feito.

* OK - Título do post não aparece no single-item do blog! E se coloca título, ele fica duplicado com o link na página do blog. Texto do list-item não está centralizando direito.

* OK - Colocar conteúdos nas páginas.

* OK - Geração de certificado do Let's Encrypt e configuração para o site ser servido por HTTPS.

---

## 9. A fazer:

[[!color  foreground=#ff0000 text="RSS/Atom tá quebrado ¬¬"]]

- Otimizar o carregamento do site. Escolha do DNS não tem impacto relevante nisso. Imagens jpg foram convertidas para png, mas ainda está pesado. **lightbox** parece resolver isso.

- No mundo ideal, cada "tipo de blog" daria ao post uma cor de fundo diferente, mas <del> precisa muita pesquisa e menos preguiça para fazer isso acontecer com Grav, acho</del> isso não é prioridade para colocar o site no ar.

<del>- Os tais botões para compartilhamento dos posts. *talvez*</del> NOPE.

- Ver se vale a pena chamar o CSS por mediaquery na página inicial, separando CSS desktop do CSS mobile (diminuindo tamanho/peso das imagens).

- Breadcrumbs (tem plugin já, mas acho que não vai ser necessário, pois os botões da barra de navegação vão indicar em qual das categorias se está... imagino

- API GNU Social para mostrar os últimos "notices" do Quitter na home -> Documentado no [fórum da igreja](https://iikb.xyz/forum/API_GNU_social/) para desenvolvermos...

- Flattr por autora

- 403 - forbidden (standard)

---

# Passo a passo para instalação do Grav

`TODO`: providenciar links de referência para as coisas em itálico. Alias, criar um mecanismo pra ikiwiki, ou descobrir se já tem, parecido com o da wikipedia pra "faltando referências".

Usando o servidor *lv1* da *igreja*.

## Achar documentação

Grav usa o próprio Grav pra providenciar uma ferramenta similar a *readthedocs*:

* <https://learn.getgrav.org/>
* <https://learn.getgrav.org/basics/installation>

## Sys Admin

### Criar usuário exclusivo

Por questões de "sempre foi assim", a primeira coisa é sempre criar um usuário específico para este fim:

    desci@lv1:~$ sudo adduser grav
    desci@lv1:~$ sudo -u grav /bin/bash
    grav@lv1:/home/desci$ cd
    grav@lv1:~$

## Composer e PHP

`TODO`: Documentar o que é e como se instala *composer*

### Instalando o Grav por composer

    grav@lv1:~$ composer create-project getgrav/grav grav

Analisando cada parte do comando:

#### composer

é o nome do software:

    grav@lv1:~$ whereis composer
    composer: /usr/local/bin/composer

#### create-project

serve pra criar um projeto a partir de um pacote, ou seja, funciona como clonar um repositório git, ou como extrair o conteúdo de um arquivo zip contendo o software "grav".

#### getgrav/grav

é o caminho para o projeto grav buscado pelo composer (não sei porque, tem que pesquisar isto)

#### grav

é o diretório local onde eu instalei o software "grav", ou seja, como eu estava na home do usuário "grav", então estes dois comandos seriam equivalentes:

    grav@lv1:~$ composer create-project getgrav/grav grav
    grav@lv1:~$ composer create-project getgrav/grav /home/grav/grav

### Mais informações sobre o composer

#### Ajuda

    grav@lv1:~$ composer -h
    Usage:
      help [options] [--] [<command_name>]
    
    Arguments:
      command                        The command to execute
      command_name                   The command name [default: "help"]
    
    Options:
          --xml                      To output help as XML
          --format=FORMAT            The output format (txt, xml, json, or md) [default: "txt"]
          --raw                      To output raw command help
      -h, --help                     Display this help message
      -q, --quiet                    Do not output any message
      -V, --version                  Display this application version
          --ansi                     Force ANSI output
          --no-ansi                  Disable ANSI output
      -n, --no-interaction           Do not ask any interactive question
          --profile                  Display timing and memory usage information
          --no-plugins               Whether to disable plugins.
      -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
      -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
    
    Help:
     The help command displays help for a given command:
     
       php /usr/local/bin/composer help list
     
     You can also output the help in other formats by using the --format option:
     
       php /usr/local/bin/composer help --format=xml list
     
     To display the list of available commands, please use the list command.

#### Lista de comandos

    grav@lv1:~$ composer list
       ______
      / ____/___  ____ ___  ____  ____  ________  _____
     / /   / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
    / /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
    \____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
                        /_/
    Composer version 1.1.1 2016-05-17 12:25:44
    
    Usage:
      command [options] [arguments]
    
    Options:
      -h, --help                     Display this help message
      -q, --quiet                    Do not output any message
      -V, --version                  Display this application version
          --ansi                     Force ANSI output
          --no-ansi                  Disable ANSI output
      -n, --no-interaction           Do not ask any interactive question
          --profile                  Display timing and memory usage information
          --no-plugins               Whether to disable plugins.
      -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
      -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
    
    Available commands:
      about           Short information about Composer
      archive         Create an archive of this composer package
      browse          Opens the package's repository URL or homepage in your browser.
      clear-cache     Clears composer's internal package cache.
      clearcache      Clears composer's internal package cache.
      config          Set config options
      create-project  Create new project from a package into given directory.
      depends         Shows which packages cause the given package to be installed
      diagnose        Diagnoses the system to identify common errors.
      dump-autoload   Dumps the autoloader
      dumpautoload    Dumps the autoloader
      exec            Execute a vendored binary/script
      global          Allows running commands in the global composer dir ($COMPOSER_HOME).
      help            Displays help for a command
      home            Opens the package's repository URL or homepage in your browser.
      info            Show information about packages
      init            Creates a basic composer.json file in current directory.
      install         Installs the project dependencies from the composer.lock file if present, or falls back on the composer.json.
      licenses        Show information about licenses of dependencies
      list            Lists commands
      outdated        Shows a list of installed packages that have updates available, including their latest version.
      prohibits       Shows which packages prevent the given package from being installed
      remove          Removes a package from the require or require-dev
      require         Adds required packages to your composer.json and installs them
      run-script      Run the scripts defined in composer.json.
      search          Search for packages
      self-update     Updates composer.phar to the latest version.
      selfupdate      Updates composer.phar to the latest version.
      show            Show information about packages
      status          Show a list of locally modified packages
      suggests        Show package suggestions
      update          Updates your dependencies to the latest version according to composer.json, and updates the composer.lock file.
      validate        Validates a composer.json and composer.lock
      why             Shows which packages cause the given package to be installed
      why-not         Shows which packages prevent the given package from being installed

## Procedimentos adicionais

O composer vai terminar com um erro de permissão, porque ele vai tentar invocar um comando sem permissões de execução. Isto é desejável.

Para concluir a instalação:

    grav@lv1:~$ cd grav
    grav@lv1:~/grav$ chmod ug+x bin/*
    grav@lv1:~/grav$ bin/grav install

### Para atualizar

    grav@lv1:~/grav$ bin/gpm selfupgrade

## Criando um site novo

Sites são chamados de "projetos" na documentação do Grav.

Embora o Grav conte com um painel de administração web que é instalável através de um plugin, tudo pode ser feito pela linha de comando que nem gente grande: <https://learn.getgrav.org/cli-console/grav-cli>

### Criando diretório para o projeto (opcional)

[[Eu|desci]] poderia criar um diretório para o site como um subdiretório do grav mesmo.

Mas como [[eu|desci]] sou organizado, [[eu|desci]] costumo criar um diretório específico para isto:

    grav@lv1:~/grav$ mkdir -p ~/public_html/grav

### Criando novo projeto

Conforme o [manual](https://learn.getgrav.org/cli-console/grav-cli):

    grav@lv1:~/grav$ bin/grav new-project ~/public_html/teste

Assumindo que o nome do site novo é "*teste*". Qualquer nome de diretório serve.

### Instalando dependências

O site novo não vem com nada, e provavelmente na hora de acessar o site, uma tela de erro vai aparecer dizendo que o tema "antimatter", que é o padrão, não existe.

Não é que não existe, é que a gente não instalou nada ainda. Se resolve assim:

    grav@lv1:~/grav$ cd ~/public_html/teste
    grav@lv1:~/public_html/teste$ bin/grav install

## Painel de administração

O fato de ter um painel de administração é de suma importância para dois tipos específicos de usuárias(os):

1. As pessoas que têm preguiça, medo de uma linha de comando, recalques, certezas, ou que são simplesmente estultas. Estas devem calar a boca e parar de encher o saco mediante a constatação de que tem ali um painelzinho bonitinho igual o do lixopress.
1. As pessoas com barreiras técnicas e políticas, como por exemplo firewall corporativo, perseguição pessoal, bloqueios de rede, monitoramento e vigilância, etc. Estas pessoas precisam de formas criativas para conseguir acessar o site para administrar e publicar sem ter restrições, censura, repressão, etc. É desejável que uma ferramenta tenha o máximo possível de interfaces de interação diferente, porque se há bloqueio de uma forma, é possível acessar por outra.

Em qualquer uma das duas situações, o painel de administração resolve problemas sociopolíticos de acesso à ferramenta.

Para instalar o painel de administração, utiliza-se o seguinte comando:

    grav@lv1:~/public_html/teste$ bin/gpm install admin

Ou então instalar do jeito difícil por sftp e descompactar o arquivo *zip* obtido pelo [github](https://github.com/getgrav/grav/releases).

[[!meta title="Grav"]]
[[!tag todo tutorial grav php composer lv1 blog site]]
